/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
package org.javaongems.runtime.http;

import java.io.IOException;

import javax.servlet.http.HttpServletResponse;

import org.apache.log4j.Logger;

/**
 * <p>Provides servlets with the ability to short circuit all control 
 * logic associated with avoiding writing to the servlet output stream
 * when a redirection has be registred via the HttpServletResponse::
 * sendRedirect() method. This class must be thrown immediately after
 * the sendRedirect method call and caught and ignored in the servlet.
 * Indeed this an abuse of the exception facility but renders a much
 * cleaner codebase.</p>
 *  
 * @author Ashin Wimalajeewa (ash)
 */
public class ExpressRedirector {
	final static private Logger LOGGER = Logger.getLogger(ExpressRedirector.class);
	
	private ExpressRedirector() {
		// nothing to do
	}
	
	/**
	 * <p>Provides the ability to silently short circuit a given
	 * http request until caught in an outer container where 
	 * control is desired again. Note, this is not really a
	 * runtime exception, more of a silent throwable. 
	 */
	static public class ShortCircuit extends RuntimeException {
	}
	
	static public void redirect(HttpServletResponse resp, String uri)
			throws IOException, ShortCircuit {
		resp.sendRedirect(uri);
		if (LOGGER.isDebugEnabled()) LOGGER.debug("redirecting to [" + uri + "]");
		throw new ShortCircuit();
	}
}
